Add LangChain workflow span support and refactor LLM invocation by wrisa · Pull Request #4449 · open-telemetry/opentelemetry-python-contrib

wrisa · 2026-04-16T20:19:19Z

Description

Introduces support for tracing LangChain workflow-level operations (first chain) via the callback handler.
Adds start/stop workflow invocation tracking alongside the existing LLM inference spans.
Refactors the callback handler to adress changes in #feat(util-genai): refactor and make API smaller and more user-friendly #4391.
Adds opentelemetry-util-genai as an explicit dependency in pyproject.toml.
Includes a workflow example (examples/workflow/main.py)
Comprehensive tests covering chain execution tracing.

See sample workflow and inference spans below,

Fixes # (issue)

Type of change

Please delete options that are not relevant.

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

Test A

Does This PR Require a Core Repo Change?

Yes. - Link to PR:
No.

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

Followed the style guidelines of this project
Changelogs have been updated
Unit tests have been added
Documentation has been updated

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds workflow-level tracing for LangChain (top-level chain runs) and refactors LLM span creation to use the newer GenAI invocation APIs, including an example and expanded test coverage.

Changes:

Add workflow invocation (INTERNAL span) start/stop/error handling via on_chain_* callbacks.
Refactor LLM spans to use InferenceInvocation (start_inference(), stop(), fail()), and introduce workflow invocation tracking.
Add opentelemetry-util-genai dependency plus a LangGraph workflow example and new tests.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
instrumentation-genai/opentelemetry-instrumentation-langchain/tests/test_workflow_chain.py	Adds unit tests validating workflow span creation, CSA propagation, and error/no-op paths.
instrumentation-genai/opentelemetry-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/invocation_manager.py	Makes invocation state nullable to support runs without an associated GenAI invocation.
instrumentation-genai/opentelemetry-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/callback_handler.py	Implements workflow spans for chains and migrates LLM handling to `InferenceInvocation`.
instrumentation-genai/opentelemetry-instrumentation-langchain/pyproject.toml	Updates core instrumentation dependency and adds explicit `opentelemetry-util-genai` dependency.
instrumentation-genai/opentelemetry-instrumentation-langchain/examples/workflow/requirements.txt	Adds dependencies for the new workflow example.
instrumentation-genai/opentelemetry-instrumentation-langchain/examples/workflow/main.py	Adds a LangGraph `StateGraph` workflow example that invokes an LLM node.
instrumentation-genai/opentelemetry-instrumentation-langchain/CHANGELOG.md	Notes the new workflow span support/refactor in the changelog.

Copilot · 2026-04-23T17:52:25Z

+        else:
+            # TODO: For agent invocation
+            self._invocation_manager.add_invocation_state(
+                run_id,
+                parent_run_id,
+                None,  # type: ignore[arg-type]
+            )
+


Nested chains are recorded in the invocation manager with invocation=None, but on_chain_end() returns early when the invocation is missing/non-WorkflowInvocation. If parent_run_id is not present in the manager (e.g., out-of-order callbacks or partial instrumentation), this creates orphaned entries that will never be cleaned up. Consider deleting the invocation state on on_chain_end() / on_chain_error() when get_invocation() returns None (or when it’s not a WorkflowInvocation), or avoid storing state at all when the parent is unknown.

Suggested change

else:

# TODO: For agent invocation

self._invocation_manager.add_invocation_state(

run_id,

parent_run_id,

None, # type: ignore[arg-type]

)

parent_invocation = self._invocation_manager.get_invocation(

run_id=parent_run_id

)

if parent_invocation is None or not isinstance(

parent_invocation, WorkflowInvocation

):

# Do not record nested chain state when the parent is unknown or

# not a workflow; otherwise we can create orphaned entries that

# on_chain_end/on_chain_error cannot clean up.

return

# TODO: For agent invocation

self._invocation_manager.add_invocation_state(

run_id,

parent_run_id,

None, # type: ignore[arg-type]

)

Copilot · 2026-04-23T17:52:26Z

+        invocation = self._invocation_manager.get_invocation(run_id=run_id)
+        if invocation is None or not isinstance(
+            invocation, WorkflowInvocation
+        ):
+            # If the invocation does not exist, we cannot set attributes or end it
+            return


Nested chains are recorded in the invocation manager with invocation=None, but on_chain_end() returns early when the invocation is missing/non-WorkflowInvocation. If parent_run_id is not present in the manager (e.g., out-of-order callbacks or partial instrumentation), this creates orphaned entries that will never be cleaned up. Consider deleting the invocation state on on_chain_end() / on_chain_error() when get_invocation() returns None (or when it’s not a WorkflowInvocation), or avoid storing state at all when the parent is unknown.

Copilot · 2026-04-23T17:52:26Z

 @dataclass
 class _InvocationState:
-    invocation: GenAIInvocation
+    invocation: Optional[GenAIInvocation]


Now that _InvocationState.invocation is Optional[GenAIInvocation], _InvocationManager.add_invocation_state(...) should accept Optional[GenAIInvocation] as well (and callers should no longer need # type: ignore[arg-type]). Updating the manager’s method signature and any related typing will keep the public surface consistent and prevent type-suppression from hiding real issues.

If you use copilot's suggestion earlier to just return when you have no invocation, we don't need to set optional here. Either path would work

Copilot · 2026-04-23T17:52:26Z

+        top_p=0.9,
+        frequency_penalty=0.5,
+        presence_penalty=0.5,
+        stop_sequences=["\n", "Human:", "AI:"],


ChatOpenAI typically expects stop (not stop_sequences) for stop tokens; using an unsupported constructor kwarg will raise at runtime and make the example fail. Update the example to use the correct parameter name(s) supported by langchain_openai.ChatOpenAI for the pinned langchain==0.3.21.

Suggested change

stop_sequences=["\n", "Human:", "AI:"],

stop=["\n", "Human:", "AI:"],

keith-decker · 2026-04-24T14:22:00Z

+# Uncomment after langchain instrumentation is released
+# opentelemetry-instrumentation-langchain~=2.0b0.dev


can delete this if not needed anymore

keith-decker · 2026-04-24T14:25:35Z

 @dataclass
 class _InvocationState:
-    invocation: GenAIInvocation
+    invocation: Optional[GenAIInvocation]


If you use copilot's suggestion earlier to just return when you have no invocation, we don't need to set optional here. Either path would work

Add workflow and refactor LLM for langchain

912b784

github-actions Bot assigned wrisa Apr 16, 2026

wrisa changed the title ~~Add workflow and refactor LLM for langchain~~ Add LangChain workflow span support and refactor LLM invocation Apr 16, 2026

wrisa added 6 commits April 20, 2026 11:27

Merge branch 'open-telemetry:main' into langchain-workflow-type

9d4876f

add workflow support and genai dependancy

1ce4cf5

fixed errors

e9fff12

fixed changelog

6e34620

fixed error

c17607d

fixed type error

a63f271

keith-decker reviewed Apr 20, 2026

View reviewed changes

Comment thread ...-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/invocation_manager.py Outdated

Comment thread ...ry-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/callback_handler.py

wrisa added 6 commits April 21, 2026 09:22

removed optional

e8be641

fixed error

a9dc188

ignore

3605631

fixed requests

4b7808f

Merge branch 'main' into langchain-workflow-type

e6d9f03

Merge branch 'main' into langchain-workflow-type

a503105

wrisa marked this pull request as ready for review April 23, 2026 16:45

wrisa requested a review from a team as a code owner April 23, 2026 16:45

Merge branch 'main' into langchain-workflow-type

dc068fb

lmolkova requested a review from Copilot April 23, 2026 17:44

Copilot AI reviewed Apr 23, 2026

View reviewed changes

Copilot started reviewing on behalf of lmolkova April 23, 2026 18:15 View session

keith-decker reviewed Apr 24, 2026

View reviewed changes

Merge branch 'main' into langchain-workflow-type

2ee7792

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add LangChain workflow span support and refactor LLM invocation#4449

Add LangChain workflow span support and refactor LLM invocation#4449
wrisa wants to merge 15 commits intoopen-telemetry:mainfrom
wrisa:langchain-workflow-type

wrisa commented Apr 16, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

keith-decker Apr 24, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

keith-decker Apr 24, 2026

Uh oh!

keith-decker Apr 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	stop_sequences=["\n", "Human:", "AI:"],
	stop=["\n", "Human:", "AI:"],

		# Uncomment after langchain instrumentation is released
		# opentelemetry-instrumentation-langchain~=2.0b0.dev No newline at end of file

Conversation

wrisa commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

How Has This Been Tested?

Does This PR Require a Core Repo Change?

Checklist:

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

keith-decker Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

keith-decker Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

keith-decker Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

wrisa commented Apr 16, 2026 •

edited

Loading